/*******************************************************************************
 * Copyright 2011 Towee.net
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *******************************************************************************/

package net.towee.server.authentication;

import javax.servlet.http.HttpSession;

import net.towee.model.account.AccountData;

import org.apache.vysper.xmpp.addressing.Entity;

/**
 * Utility class for managing the session's authentication status.
 * 
 * @author c58
 */
public interface SessionAuthManager {

	/**
	 * Get the participant id of the currently logged in user from the user's
	 * HTTP session.
	 * 
	 * If the session is null, or if the user is not logged in, this function
	 * try restore session by given coockiRememberId. If this try is unsuccess,
	 * this function return null
	 * 
	 * @param session
	 *            The user's HTTP session, usually obtained from
	 *            request.getSession(false);
	 * @return the user's participant id, or null if the user is not logged in.
	 */
	String getLoggedInUser(HttpSession session, String cookieRemeberId);

	/**
	 * Bind the user's participant id to the user's session.
	 * 
	 * This records that a user has been logged in.
	 * 
	 * @param session
	 *            The user's HTTP session, usually obtained from
	 *            request.getSession(true);
	 * @param id
	 *            the user who has been logged in
	 */
	void setLoggedInUser(HttpSession session, String id);

	/**
	 * Log the user out.
	 * 
	 * If session is null, this function has no effect.
	 * 
	 * @param session
	 *            The user's HTTP session, obtainable from
	 *            request.getSession(false);
	 */
	void logout(HttpSession session);

	/**
	 * Get a user's HttpSession from their session token.
	 * 
	 * @param token
	 *            the session token. Eg, "JSESSION=abcdef123567890"
	 * @return the user's HttpSession, or null if the token is invalid.
	 */
	HttpSession getSessionFromToken(String token);

	/**
	 * @param session
	 * @return true if user with given session authorized
	 */
	boolean isLoggedIn(HttpSession session);
	
	AccountData getLoggedInAccount(HttpSession session);

	/**
	 * @param session
	 * @return JID of current session or generate RuntimeException if user not logged in
	 * 		   because it not be happen while all requests to the servlet filtered.
	 */
	Entity getSessionJID(HttpSession session);
}
